Montage is a general astronomical image toolkit with facilities for reprojection, background matching, coaddition and visualization. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.
Montage source code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI ("pip install MontagePy"). See http://montage.ipac.caltech.edu/ for more information.
MontagePy.main modules: mCoverageCheck¶
A large percentage of the Montage modules focus on processing a set of images (often retrieved from a mission archive); projecting them to a common frame, adjusting their background levels as a set, and coadding them into a mosaic.
Starting with archive access, this mosaicking sequence uses the following modules:
- mHdr — Make a template FITS header for a region.
- mArchiveList — Identify archive images for a region.
- mArchiveGet and mArchiveExec — Retreive archive images individually or as a set.
- mImgtbl — Mine a set of images for metadata (and in particular sky coverage).
- mCoverageCheck — Subset an image list based on a region specification.
- mMakeHdr or mHdr — Make a template FITS header bounding a set of images or the header for a sky region.
- mProject / mProjectPP / mProjectQL and mProjExec — Reproject images individually or as a set.
- mOverlaps — Determine which images in a set overlap each other.
- mDiff/mFitplane and mDiffFitExec — Fit the differences between images one pair at a time or all the differences.
- mBgModel — Model a set of differences to determine the "best" background correction for each image.
- mBackground and mBgExec — Background-correct an image or a set of images.
- mAdd — Coadd reprojected (and background corrected) images into a final mosaic.
This page is focused on the details of one of these modules: mCoverageCheck. For a broader context, please see Building a Mosaic with Montage or the one shot version if you just want to see the commands.
Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.
mCoverageCheck Python Help¶
from MontagePy.main import mCoverageCheck, mViewer
help(mCoverageCheck)
mCoverageCheck Example¶
The M17 dataset we are using has 48 images.We would like know which of them overlap a 0.20 degree radius circle centered on M17 itself.
import os
try:
os.makedirs('work/M17')
except:
pass
rtn = mCoverageCheck('M17/rimages.tbl',
'work/M17/subset.tbl',
narray=3, array = [275.19629, -16.17153, 0.2],
mode=2)
print(rtn)
Here is a mosaic of the full dataset with the images identified above as overlapping with a 0.3 degree circle centered on M17 outlined:
from IPython.display import Image
rtn = mViewer('-color black -imginfo work/M17/subset.tbl \
-ct 1 -gray M17/mosaic.fits -2s max gaussian-log \
-out work/M17/coverage.png', '', mode=2)
Image(filename='work/M17/coverage.png')
Montage functions return JSON structures. They always include a status (0: success; 1: error) and a variable number of informational parameters.
Error Handling¶
If mCoverageCheck encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.
For instance, if the user specifies a table that doesn't exist:
rtn = mCoverageCheck('M17/unknown.tbl',
'work/M17/subset.tbl',
narray=3, array = [275.19629, -16.17153, 0.2],
mode=2)
print(rtn)
Classic Montage: mCoverageCheck as a Stand-Alone Program¶
mCoverageCheck Unix/Windows Command-line Arguments¶
mCoverageCheck can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mCoverageCheck [-s statusfile] in.tbl out.tbl -
If you are writing in C/C++, mCoverageCheck can be accessed as a library function:
/*-***********************************************************************/ /* */ /* mCoverageCheck */ /* */ /* Montage is a set of general reprojection / coordinate-transform / */ /* mosaicking programs. Any number of input images can be merged into */ /* an output FITS file. The attributes of the input are read from the */ /* input files; the attributes of the output are read a combination of */ /* the command line and a FITS header template file. */ /* */ /* This module, mCoverageCheck, can be used to subset an image */ /* metadata table (containing FITS/WCS information or image corners) */ /* by determining which records in the table represent images that */ /* overlap with a region definition (box or circle on the sky) given */ /* on the command line. */ /* */ /* char *path Path to image files (table contains relative */ /* paths) */ /* char *infile Table of image metadata */ /* char *outfile Output table of matching records */ /* */ /* int mode There are six 'modes' of use, depending on */ /* the region to be checked is defined: */ /* 0 (POINTS), a set of convex polygon vertices; */ /* 1 (BOX), box center and sizes; 2 (CIRCLE), */ /* center and radius of a cone on the sky; */ /* 3 (POINT), a single point on the sky; */ /* 4 (HEADER), a FITS header template (file); */ /* and 5 (CUTOUT),and 5 (CUTOUT), like box but */ /* uses the full image file WCS and updates the */ /* record to indicate what subset of each image */ /* overlaps the box. */ /* */ /* char *hdrfile FITS header template file; only used by mode */ /* 4 (HEADER) above. */ /* */ /* int narray Size of the 'array' of real numbers to use. */ /* double array[] Array of real numbers. The size and use */ /* depend on mode. For instance for mode */ /* 0 (POINTS) the number is twice the number */ /* of vertices in the polygon. */ /* */ /* int debug Debugging output level */ /* */ /*************************************************************************/ struct mCoverageCheckReturn *mCoverageCheck(char *path, char *infile, char *outfile, int modein, char *hdrfile, int narray, double *array, int debug)
Return Structure
struct mCoverageCheckReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
int count; // Number of images matching region
};